home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 33 / Amiga Format AFCD33 (Issue 117, Dec 1998).iso / -seriously_amiga- / programming / c / qtools0.2 / archives / qtools0.2-src.lha / docs / qtools.doc
Text File  |  1998-07-10  |  17KB  |  436 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                                     QuakeTools-library
  7.                                        Version 0.0
  8.                      Copyright © by Niels Froehling (Dyna-Tech) 1998
  9.  
  10.  
  11.        idea:
  12.        
  13.          the intention to write this was to bind all the (sometimes not easy to find) basic
  14.          functions to create and modify all the different files of quake. i know, there are
  15.          allready the sources from mr. carmack, but ive written lots of extensions, sometimes
  16.          his code is a bit confusing, and as we all now we can read own code better than code
  17.          from others :).
  18.          this is an open project, so any programmer who wants to put his ideas or descriptions
  19.          into this, can join. there is so much left and undocumented i havnt enough time to do
  20.          all of it.
  21.          as a beginning this code could act as a quake-dokumentation-project too (eg. combined
  22.          together with "the unofficial quake-faq").
  23.        
  24.        contact:
  25.        
  26.          email
  27.           <Niels.Froehling@Informatik.Uni-Oldenburg.DE>
  28.           
  29.          snailmail
  30.           Niels Froehling
  31.           Bardieksweg 28
  32.           26125 Oldenburg
  33.           Germany
  34.        
  35.        status:
  36.        
  37.      This program is free software; you can redistribute it and/or modify
  38.      it under the terms of the GNU General Public License as published by
  39.      the Free Software Foundation; either version 2 of the License, or
  40.      (at your option) any later version.
  41.  
  42.      This program is distributed in the hope that it will be useful,
  43.      but WITHOUT ANY WARRANTY; without even the implied warranty of
  44.      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  45.      GNU General Public License for more details.
  46.  
  47.      You should have received a copy of the GNU General Public License
  48.      along with this program; if not, write to the Free Software
  49.      Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  50.  
  51.          read it carefully, aspecialy if you drive windows or something like that.
  52.          
  53.          bsptomap:
  54.           "you are free to use this program
  55.            you are free to use/modify/compile source code
  56.            you can do anything you want with it"
  57.           means: the code from bsptomap falls under the GPL too
  58.          
  59.          qutils/exdawn:
  60.           no comment about copyrights
  61.           means: the code from qutils falls under the GPL too
  62.          
  63.          unqcc:
  64.           "Do whatever you like with it."
  65.           means: the code from qcc falls under the GPL too
  66.          
  67.          summary:
  68.           ALL of this code falls under the GPL. in short: every modification of the code
  69.           must be reported and send to the programmer(s) of this code, and is distributed
  70.           under the GPL too.
  71.           you are NOT allowed to take money more than the costs of the medium on it is copied.
  72.        
  73.        programmer(s)/credits:
  74.        
  75.          Janis Jagars <ppsaikne@mail.vernet.lv>
  76.          John Carmack <???>
  77.          Christian Knauer <cnknauer@cip.informatik.uni-erlangen.de>
  78.          Ben Cohee <benco@gisco.net>
  79.          Mads Bondo Dydensborg <madsdyd@diku.dk>
  80.          Niels Froehling <Niels.Froehling@Informatik.Uni-Oldenburg.DE>
  81.        
  82.        maintainer:
  83.        
  84.          Niels Froehling <Niels.Froehling@Informatik.Uni-Oldenburg.DE>
  85.          
  86.        options:
  87.  
  88.      -c <colormap>       quake colormap lump
  89.      -d <destdir>        alternative destination directory including "/" at the end
  90.      -dither [<value>]   dither floyd-steinberg with this error
  91.                   (a little bit complicate: the standard error diffusion
  92.                    with floyd steinberg is to divide by 16 and add con-
  93.                    stant parts of the error to neighnour pixels. the value
  94.                    is valid from 16 to 256 which means: is the error-ammount
  95.                    for a pixel 3 we use 3/16 of the error in default. if the
  96.                    amount is 32 we use 3/32, so the error-diffusion is halfed.
  97.                    in general we could say, the higher the value, the less
  98.                    qtools do error-diffusion (an invinite value means NO
  99.                    error-diffusion, in practice the errors maximum is 256).
  100.                    default is 16.
  101.      -smooth [<value>]   smooth the pictures while converting (valid from 1 to 256)
  102.                   meaning, all upto 256th of the 8 neighbour-pixels influences
  103.                   the original pixel-color. default is 2.
  104.      -l <darkness>       take this darkness-level
  105.      -lump/-mip          specifies pic-conversion (in general for directory-
  106.                   conversions without "-o")
  107.      -mip0               store only the first mip instead of all four (only
  108.                   for wads)
  109.      -lz                 compress data with lz77 (only for wads)
  110.                  (only available in the executeable for amiga, i will
  111.                   compile it for other 68k-systems on demand. its my
  112.                   algorithm and my implementation, so im not interesting
  113.                   in a publication for free (eah, i do only have 68k-code))
  114.      -ns                 do not write index-files
  115.      -o <file>           specify archive-content or output-name
  116.      -p <palette>        quake palette lump
  117.      -ppm/-jpg/-png         convert pictures and palettes to ppm/jpg/png
  118.      -r                  recurse extracting
  119.      -<qbsp/light/vis>   support for ALL option that qbsp, light and vis have. except
  120.                   threads
  121.      -waterlit         water and slime get shadows
  122.      -watervis         look through water (GLQuake)
  123.      -slimevis         look through slime (GLQuake)
  124.      -pp "<commandline>" you can specify a preprocessor like cpp to parse
  125.                   QuakeC-files before the compiler. if you want to give
  126.                   commandlines to it, it is a must to set quotation-marks
  127.                   (eg. "cpp -P" is perfectly valid), afterwards qtools inter-
  128.                   prets the commandline for itself
  129.  
  130.        commands:
  131.  
  132.      a                   add
  133.      d                   delete (unimplemented)
  134.      l                   list (default)
  135.      r                   replace (unimplemented)
  136.      u                   update (unimplemented)
  137.      v                   view (unimplemented)
  138.      x                   extract
  139.  
  140.        environment:
  141.     
  142.      QUAKE_PALETTE         the location of the default "palette.lmp"
  143.                   (default is "palette.lmp")
  144.      QUAKE_COLORMAP         the location of the default "colormap.lmp"
  145.                   (default is "colormap.lmp")
  146.      QUAKE_WADFILE         the location of the default wad for bsps, you can put more than
  147.                   one wad into the line: "test1.wad; medivial.wad; rogue.wad"
  148.                   (no default)
  149.      QUAKE_WADDIR         the location of the default directory to parse for miptexs, you
  150.                  can put more than one dir into the line: "test1.wad; medivial.wad;
  151.                  rogue.wad"
  152.                   (default is current directory)
  153.  
  154.        extensions:
  155.        
  156.     floating points in every data-file qbsp/vis uses: map/prt/h?/pts
  157.     
  158.     multiple wads in the "wad" and "_wad" keywords: "test1.wad; medivial.wad; rogue.wad"
  159.     of map-files
  160.     
  161.     "dir" keyword in map files, if qtools scans for textures in bsp-creation, it scans
  162.     the dirs (non-recursive) and loads the textures from every fileformat it can load
  163.     multiple dirs are valid too: "test1.dir; /tmp/medivial-contents; ~/crap-tests"
  164.     (it does NOT search for wads in these directories, only images)
  165.  
  166.        some features in short:
  167.        
  168.         read/writes picture formats:
  169.         
  170.          ppm/pgm/png/jpg
  171.         
  172.         read/writes 3d formats:
  173.         
  174.          tddd
  175.          
  176.         read/writes quake formats:
  177.         
  178.          wad/(bsp/vis/lit/prt/h?/map)/pak/(qc/dat)/mip/lmp
  179.          
  180.         others:
  181.         
  182.          can compress wads
  183.          can use fs-dithering
  184.          uses high quality mipmap-scaling
  185.          build in script-system with recursion-capabilities
  186.          can load pictures directly into bsps
  187.          uses less memory
  188.          error robust
  189.          can parse entire directories and perform the default actions to every file
  190.           and subdirectory
  191.          can extract bsp/pak recursively
  192.  
  193.        available modes (examples):
  194.     
  195.     notes:
  196.     
  197.      qtools is able to read AND write all of its datas, so you could
  198.      make make it a ppm2png-converter or vice versa with the limitation, that the
  199.      pictures will be remapped to the quake-colors, but that need not to be a
  200.      limitation, maybe a feature.
  201.      
  202.      sometimes you can suspress the "x" if you define a clear (from the program
  203.      understandable) output like "qtools quake.wad -o *slime1".
  204.      
  205.      sometimes you can suspress the "a" if you define a clear (from the program
  206.      understandable) output like "qtools *slime1.mip -o quake.wad"
  207.      
  208.      it is possible to emulate some behaviours of other programs like mergewad:
  209.      
  210.       to merge to wads you should type something like this:
  211.       
  212.        qtools a first.wad -o merged.wad
  213.        qtools a second.wad -o merged.wad
  214.        qtools a third.wad -o merged.wad
  215.        qtools a fourth.wad -o merged.wad
  216.        ...
  217.       
  218.       to sub wads:
  219.       
  220.        qtools v first.wad
  221.        rename first.idx delfirstinmerged.idx
  222.        replace "update" with "delete" in delfirstinmerged.idx
  223.        replace "first.wad" with "merged.wad" in delfirstinmerged.idx
  224.        qtools delfirstinmerged.idx
  225.       
  226.      qtools does not extract wads out of paks nor converts pictures. you will
  227.      get the raw data only. try "-r" for recursive, then all the contents of
  228.      the pak will be postprocessed by qtools. WARNING: recursive means really
  229.      recursive: pak->bsp->wad->pic and pak->bsp->map or pak->dat->src. every-
  230.      thing will be processed!
  231.     
  232.      the format of "-o <file>" is very error-resistent. these:
  233.       -o *slime1
  234.       -o *slime1.
  235.       -o *slime1.<whatever you think>
  236.      extract surely "*slime1" out of bsps and wads.
  237.      one exception is "-o *slime1.<whatever you think>":
  238.       -o *slime1.ppm            extracts to a ppm
  239.       -o *slime1.png            extracts to a png
  240.       -o *slime1.<whatever other you think> extracts to a raw-mipmap
  241.      mipmap does not have any identifiers, its up to you to remember, which
  242.      files are mips and which not.
  243.     
  244.      there are some special word on bsps. i have split up the definition of a
  245.      bsp in several parts:
  246.       test.bsp
  247.      contains
  248.       test.map (decompiled bsp, map-format)
  249.       test.iob (decompiled bsp, imagine-object-format)
  250.       test.wad (textures)
  251.       test.lit (raw)
  252.       test.vis (raw)
  253.      so if you type "qtools x test.bsp -o test.vis" you get the raw-visdata.
  254.      all names, that are not of the form "<filebase>.<map/wad/lit/vis>" are
  255.      accepted as texturenames. "qtools x test.bsp -o *slime1" extracts the
  256.      texture "*slime1" seperatly.
  257.     
  258.     directory-structures and default outputs:
  259.     
  260.      if the output-name do not specify an alternate directory (like: -o /tmp/test.map)
  261.      all files will be saved to <filebase>.<dir>/<filebase>.<ext> or (in case of
  262.      qtools test1234.bsp -o test4321.map) <oldfilebase>.<dir>/<newfilebase>.<ext>
  263.      
  264.      if you specify a destdir, its the same as above <destdir>/<filebase>.<dir>/<filebase>.<ext>
  265.      except you do something like this: qtools -d /tmp/ test.bsp -o /tmp2/bla/test.map
  266.      produces without checking /tmp/tmp2/bla/test.map, which is invalid. in that case
  267.      the dirpart of the output is stripped resulting in /tmp/test.dir/test.map
  268.      
  269.      it is reommended to use the default hierarchy the program offers and move data
  270.      only via directories or partitions, leave the structure in it intact:
  271.      
  272.      /quake
  273.      /quake/id1
  274.      /quake/id1/pak0.pak                (results from below)
  275.      /quake/id1/pak0.idx                (file to build data recursive)
  276.      /quake/id1/pak0.dir
  277.      /quake/id1/pak0.dir/progs.dat            (results from below)
  278.      /quake/id1/pak0.dir/progs.dir
  279.      /quake/id1/pak0.dir/progs.dir/progs.src
  280.      /quake/id1/pak0.dir/progs.dir/*.qc
  281.      /quake/id1/pak0.dir/gfx
  282.      /quake/id1/pak0.dir/maps
  283.      /quake/id1/pak0.dir/maps/start.bsp        (results from below)
  284.      /quake/id1/pak0.dir/maps/start.dir
  285.      /quake/id1/pak0.dir/maps/start.dir/start.map
  286.      /quake/id1/pak0.dir/maps/start.dir/start.wad
  287.      /quake/id1/pak0.dir/maps/start.dir/start.prt
  288.      /quake/id1/pak0.dir/maps/start.dir/...
  289.      /quake/id1/pak0.dir/progs
  290.      /quake/id1/pak0.dir/sound...
  291.     
  292.     patterns:
  293.     
  294.      all form of patterns are allowed so
  295.       qtools -png -r -wad x *.bsp blabla/*.wad ../pak*.pak
  296.      extracts _all_ contents of matching files, all pictures will be converted
  297.      to png-pictures, the rest will be stored as is. additional the resulting
  298.      wad from the bsps will be converted to pngs and all contents of the pak
  299.      will be postprocessed (wad->pictures, bsp->wad->pictures, bsp->map ...).
  300.      
  301.      on some OSs the character "*" is reserved for pattern-matching (i think
  302.      dos and windows and nt are the only one). as a result on that platforms
  303.      you are NOT able to extract warp-textures that begins with a "*" (bsp->wad
  304.      is okay). hint: buy something like linux. [evilgrin]
  305.     
  306.     defaults:
  307.     
  308.      qtools test.bsp
  309.       list the contents of the bsp, that means all textures and the statistics
  310.      
  311.      qtools test.idx
  312.       processes the script "test.idx"
  313.      
  314.      qtools test.pak
  315.       list the contents of the pak
  316.      
  317.      qtools test.wad
  318.       list the contents of the wad
  319.      
  320.      qtools test.dir
  321.       processes all files and directories in test.dir with the defaults above
  322.      
  323.     extracts:
  324.     
  325.      qtools x test.bsp
  326.       extracts the contents of the bsp, that means all textures and the statistics
  327.      
  328.      qtools x test.idx
  329.       processes the script "test.idx"
  330.      
  331.      qtools x test.pak
  332.       extracts the contents of the pak
  333.      
  334.      qtools x test.wad
  335.       extracts the contents of the wad
  336.      
  337.      qtools x test.dir
  338.       processes all files and directories in test.dir with the defaults above
  339.      
  340.     modifiers:
  341.  
  342.      qtools -ppm *.mip
  343.       converts all mips to ppm
  344.       
  345.      qtools -png *.mip
  346.       converts all mips to png
  347.  
  348.      qtools -mip *.png -o png.wad
  349.       converts all pngs to mipmaps in pngs.wad
  350.       
  351.      qtools -mip -dither 16 *.png -o png.wad
  352.       converts all pngs to mipmaps in pngs.wad with dither and error diffusion of 1
  353.       
  354.      qtools -lump *.png -o png.wad
  355.       converts all pngs to consolepics in pngs.wad
  356.       
  357.      qtools -mip -mip0 *.png -o png.wad
  358.       converts all pngs to mipmaps that contains only the first mipmap in pngs.wad
  359.       (probably not readable for other tools)
  360.      
  361.       qtools -mip -lz *.png -o png.wad
  362.       converts all pngs to mipmaps in pngs.wad that are compressed
  363.       (surely not readable for other tools)
  364.       
  365.      qtools -mip -mip0 -lz *.png -o png.wad
  366.       converts all pngs to mipmaps that contains only the first mipmap in pngs.wad
  367.       and that are compressed
  368.       (surely not readable for other tools)
  369.  
  370.      qtools -ppm -d /usr/home/quake *.mip
  371.       converts all mips to ppm in the directory /usr/home/quake
  372.       
  373.      qtools -png *.mip -p /bullshit/quake/zer/gfx/colormap.lmp
  374.       converts all mips to png and uses the /bullshit/quake/zer/gfx/colormap.lmp
  375.       colormap instead of quakes (same for palettes)
  376.  
  377.        scripting:
  378.  
  379.     common commands:
  380.      "process <file>.<ext>"               -> take this file upto
  381.      "finish <file>.<ext>"                -> here
  382.      "list <file>.<ext>"              -> list the contents
  383.      "view <file>.<ext>"              -> view the pictures or texts in a window, or whatever
  384.  
  385.      sub-commands:
  386.       "update <file>.<ext> as <name>"     -> add if not exists, replace if newer
  387.       "replace <file>.<ext> as <name>"    -> replace if exists, do NOT add
  388.       "add <file>.<ext> as <name>"        -> add if not exists, do NOT replace
  389.       "delete <name>"                     -> delete if exists
  390.       "extract <name> as <file>.<ext>"    -> extract if exists
  391.  
  392.         currently implemented are only add/extract
  393.         
  394.        todo:
  395.        
  396.         use zlib instead of own compression algorithm? (already in, but only used for png)
  397.         make-like timestamp-updating?
  398.         lot of dokumentation (the whole source)
  399.         support for quake2
  400.         support fr the extensions of bsp/worldcraft/...
  401.         ... (too much)
  402.  
  403.        used code:
  404.        
  405.         ive ripped code from
  406.         
  407.          qcc      - look at ripped/quakeutils.txt
  408.           modified to use autoexpanded memory-pools
  409.          
  410.          qbsp     - look at ripped/quakeutils.txt (also used: hipnotics qbsp)
  411.           modified to use autoexpanded memory-pools
  412.           modified to make waterleafs and/or slimeleafs visible
  413.           modified to use dynamic face-sizes
  414.           modified to read from special wads and entire directories with pictures (ppm/png/jpg/mip/lmp)
  415.           modified to read and write floating points to and from every textfile (better accuracity)
  416.           modified to read multiple wads
  417.           modified to scan multiple dirs
  418.           
  419.          light    - look at ripped/quakeutils.txt (also used: hipnotics light)
  420.           modified to use autoexpanded memory-pools
  421.           modified to make water and/or slime with lightstyles
  422.           modified to make the qrad3-algorithms available to quake1
  423.           
  424.          vis      - look at ripped/quakeutils.txt
  425.           modified to use autoexpanded memory-pools
  426.           modified to read floating points from portal-file
  427.  
  428.          unqcc    - look at ripped/unqcc099.txt
  429.           modified to use autoexpanded memory-pools (unqcc itself contains code from advqcc4)
  430.  
  431.          bsptomap - look at ripped/bsptomap.txt
  432.           completly rewritten, only the concept is used
  433.  
  434.          yavis    - with permission of Mads Bondo Dydensborg
  435.           thanks a lot for his fast response and the possibility to use and publish his code under the GPL
  436.